home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 26 / Cream of the Crop 26.iso / program / qlib205.zip / QLIB.ZIP / TXT / VIDEO.TXT < prev    next >
Text File  |  1997-06-17  |  16KB  |  380 lines
  1. Video Drivers (QLIB v2.02+)
  2.  
  3. Header files:
  4.   C: video.h
  5.   ASM: video.inc
  6.  
  7. Notes:
  8.   All functions can be used in ANY video mode except for the palette
  9.     things in modes with bpp>8.
  10.  
  11. -----------------------------------------------------------------------------
  12. Function: g_getmode(word x,word y,byte bpp)
  13. Expects: x,y,bpp - x/y Res and BPP (bits per pixel) desired
  14. Outputs:
  15.   if successful the mode is available and one of the following is returned:
  16.     G_VGA = the mode is a VGA mode (320x200x8bit)
  17.     G_VESA = the mode is a VESA mode
  18.     G_MODEX = the mode is a modeX mode
  19.   if not successful
  20.     AX = ERROR (-1)
  21. Notes:
  22.   If you are using these grafix routines do not call INT 10h to change the
  23.   video mode at anytime, even to switch to text mode.  See also t_setmode()
  24. -----------------------------------------------------------------------------
  25. Function: g_setmode(void)
  26. Expects: nothing.
  27. Outputs: nothing.
  28. Notes:
  29.   Sets last mode successful returned by g_getmode()
  30. -----------------------------------------------------------------------------
  31. Function: t_setmode(word x,word y)
  32. Expects: (x,y) = text rows/columns
  33. Outputs: nothing.
  34. Notes:
  35.   Sets the video mode to text mode with x,y.
  36.   Currently only 80x25 and 80x50 are supported.
  37. -----------------------------------------------------------------------------
  38. Function: t_savestate(void)
  39. Expects: nothing
  40. Outputs: (void *)
  41. Notes:
  42.   Saves the entire state of the video card. For use in text mode only!
  43.   This function will alloc RAM as needed using malloc()
  44. -----------------------------------------------------------------------------
  45. Function: t_restorestate(void *vstate)
  46. Expects: vstate which was returned by t_savestate()
  47. Outputs: nothing
  48. Notes:
  49.   Restores video state using vstate that was returned by t_savestate().
  50.   Does NOT free memory malloc()'ed by t_savestate().
  51.   Use free() to free the memory when you no longer need it.
  52. -----------------------------------------------------------------------------
  53. Function: g_waitvsync(void)
  54. Expects: nothing.
  55. Outputs: nothing.
  56. Notes:
  57.   Waits till there is a v sych (use this before palette changes etc.)
  58. -----------------------------------------------------------------------------
  59.   VESA Specific Routines
  60. These funcs are avail only if you want to view VESA info but it is not
  61. necessary to use them to use VESA.
  62. -----------------------------------------------------------------------------
  63. Function: vesa_init(void)
  64. Expects: nothing.
  65. Outputs:
  66.   if successful
  67.     AX = VESA version  (BCD coded ie: v2.00 = 200h and v1.20 = 102h)
  68.   if not successful
  69.     AX = ERROR (-1)
  70. -----------------------------------------------------------------------------
  71. Function: vesa_func06(void)
  72. Expects:    BL   = 00h          Set Scan Line Length in Pixels
  73.                  = 01h          Get Scan Line Length
  74.                  = 02h          Set Scan Line Length in Bytes
  75.                  = 03h          Get Maximum Scan Line Length
  76.             CX   =         If BL=00h  Desired Width in Pixels
  77.                            If BL=02h  Desired Width in Bytes
  78.                            (Ignored for Get Functions)
  79. Output:     AX   =         VBE Return Status
  80.             BX   =         Bytes Per Scan Line
  81.             CX   =         Actual Pixels Per Scan Line
  82.                            (truncated to nearest complete pixel)
  83.             DX   =         Maximum Number of Scan Lines
  84. Notes:
  85.   VBE Function 06h - Set/Get Logical Scan Line Length
  86.   Directly calls INT 10h AX=4F06h;
  87.   Calling this function saves the "Bytes Per Scan Line" returned
  88.     in BX which is required for correct operation of vesa_setstart().
  89. -----------------------------------------------------------------------------
  90. Function: vesa_setstart(dword start,dword scan)
  91. Expects:
  92.   start = pixel start
  93.   scan = scan line
  94. Notes:
  95.   This sets the starting position printed on screen (the physical upper-left
  96.     corner of the screen within the logical video memory)
  97.   Using this function will mess up most the grafix functions provided.
  98. -----------------------------------------------------------------------------
  99. Function: vesa_firstmode()
  100. Expects:  nothing
  101. Returns:  if successful:
  102.              EAX = 0
  103.              vesa_modeinfo struct holds info about first mode
  104.           if unsuccessful:
  105.              EAX = -1 (ERROR)
  106.              vesa_modeinfo struct is undefined
  107. Notes:
  108.   Returns info about the 1st mode available.  If this fails
  109.     there are NO available modes.
  110.   Only modes that hareware supports shall be returned.
  111. -----------------------------------------------------------------------------
  112. Function: vesa_nextmode()
  113. Expects:  nothing
  114. Returns:  if successful:
  115.              EAX = 0
  116.              vesa_modeinfo struct holds info about mode
  117.           if unsuccessful:
  118.              EAX = -1 (ERROR)
  119.              vesa_modeinfo struct is undefined
  120. Notes:
  121.   Returns info about next mode available.  If this fails
  122.   there are no more available modes.
  123.   Only modes that hareware supports shall be returned.
  124.   You may use vesa_firstmode() and vesa_nextmode() as many times as
  125.     you like to look thru the VESA modes.
  126. -----------------------------------------------------------------------------
  127.   Standard Video Routines
  128. -----------------------------------------------------------------------------
  129. Function: g_setbuf(void * temparea)
  130. Expects: temparea - temp area for driver to use
  131. Outputs: nothing.
  132. Notes:
  133.   Sets the block of RAM that is used to copy to video RAM by g_copy()
  134.   See Appendix A below for explaintion of this function.
  135. -----------------------------------------------------------------------------
  136. Function: g_copy(void)
  137. Expects: nothing.
  138. Outputs: nothing.
  139. Notes:
  140.   Copys RAM from temparea to video RAM.
  141.   This function can NOT be called during an IRQ handler.
  142.   See Appendix A below for explaintion of this function.
  143. -----------------------------------------------------------------------------
  144. Function: g_setpal(void * pal)
  145. Expects: pal - 768 bytes representing the data
  146. Outputs: nothing.
  147. Notes:
  148.   Sets the entire 256 color palette of the VGA card.
  149. -----------------------------------------------------------------------------
  150. Function: g_setcol(byte c,byte r,byte g,byte b)
  151. Expects: c - color # to change
  152.          r,g,b - red/green/blue intensitys
  153. Outputs: nothing.
  154. Notes:
  155.   Sets one color in the 256 color palette of the VGA card.
  156.   The intensitys can be from 0 to 63 each.
  157. -----------------------------------------------------------------------------
  158. Function: g_cls(void)
  159. Expects: nothing.
  160. Outputs: nothing.
  161. Notes:
  162.   Clears the temp area with 0x00 and then calls g_copy().
  163. -----------------------------------------------------------------------------
  164. Function: g_get(byte * buf,word x1,word y1,word x2,word y2)
  165. Expects: buf = RAM to store grafix image
  166.          (x1,y1)-(x2-y2) = dimension of image to get
  167. Outputs: nothing.
  168. Notes:
  169.   Copies a rectangle image from the temp area to buf. (NOT the video RAM)
  170.   No off-screen clipping is performed.
  171. -----------------------------------------------------------------------------
  172. Function: g_put(byte * buf,word x1,word y1,word x2,word y2)
  173. Expects: buf = RAM to get grafix image from
  174.          (x1,y1)-(x2-y2) = dimension of image to put
  175. Outputs: nothing.
  176. Notes:
  177.   Copies a rectangle image from the buf to temp area. (NOT the video RAM)
  178.   No off-screen clipping is performed.
  179. -----------------------------------------------------------------------------
  180. Function: g_put0(byte * buf,word x1,word y1,word x2,word y2)
  181. Expects: buf = RAM to get grafix image from
  182.          (x1,y1)-(x2-y2) = dimension of image to put
  183. Outputs: nothing.
  184. Notes:
  185.   Copies a rectangle image from the buf to temp area. (NOT the video RAM)
  186.   No off-screen clipping is performed.
  187.   This call is identical to g_put() except this func will be plot color 0
  188.   pixels.
  189. -----------------------------------------------------------------------------
  190. Mouse Services
  191.   Make sure to read Appendix B to see how these functions work in text mode.
  192. -----------------------------------------------------------------------------
  193. Function: mouse_init(void)
  194. Expects: nothing.
  195. Outputs:
  196.   if successful (mouse driver was detected)
  197.     AX = 0
  198.   if not successful (no mouse driver detected)
  199.     AX = ERROR (-1)
  200. -----------------------------------------------------------------------------
  201. Function: mouse_setcursor(byte * img,word xsiz,word ysiz,word hsx,word hsy)
  202. Expects: img = cursor image
  203.          xsiz = X size of cursor
  204.          ysiz = Y size of cursor
  205.          hsx,hsy = hot spot of cursor
  206. Outputs: nothing.
  207. Notes:
  208.   This function must be called before using mouse_on().
  209.   The image must be the right color depth for the current grafix mode.
  210.   The hot spot is an offset from the top-left corner of the cursor.
  211.   This may be called when cursor is visable.
  212. -----------------------------------------------------------------------------
  213. Function: mouse_setcursor_text(byte color)
  214. Expects: color = color of mouse cursor
  215. Outputs: nothing.
  216. Notes:
  217.   This function must be called before using mouse_on().
  218.   This may be called when cursor is visable.
  219.   The color will simply be XORed into the text video memory right after
  220.     the char at that position.
  221.   color = (colour_desired) << 4;
  222.   Therefore the color_desired can be from 0-15.  If the other bits are
  223.     set the mouse cursor may cause letters to blink, etc.
  224. -----------------------------------------------------------------------------
  225. Function: mouse_setspd(byte xratio,byte yratio)
  226. Expects: xration = speed the cursor travels across screen
  227.          yration = speed the cursor travels up-down screen
  228. Outputs: nothing.
  229. Notes:
  230.   Valid speeds are (1=fastest ... 4=slowest)
  231.   This may be called when cursor is visable.
  232. -----------------------------------------------------------------------------
  233. Function: mouse_setwin(word x1,word y1,word x2,word y2)
  234. Expects: (x1,y1)-(x2,y2) = rectangle box coords
  235. Outputs: nothing.
  236. Notes:
  237.   Sets window that mouse is allowed to be in (with respect to hotspot).
  238.   Mouse will be moved to within box and will not be able to leave area.
  239. -----------------------------------------------------------------------------
  240. Function: mouse_on(void)
  241. Expects: nothing.
  242. Outputs: nothing.
  243. Notes:
  244.   Shows the mouse on screen.
  245. -----------------------------------------------------------------------------
  246. Function: mouse_off(void)
  247. Expects: nothing.
  248. Outputs: nothing.
  249. Notes:
  250.   Hides the mouse.  You must call this before changing to another video
  251.     mode if the mouse is currently shown.
  252.   You do not need to call mouse_off() to edit the temparea or when using
  253.     g_copy()
  254. -----------------------------------------------------------------------------
  255. Function: mouse_setuser(dword user,struct mouse_user *)
  256. Expects: user = your function offset
  257.          mouse_user = ptr to mouse_user struct
  258. Outputs: nothing.
  259. Notes:
  260.   When ever the mouse is moved or a button is pushed/released the user
  261.     function will be called.
  262.   Your function will be executing in an IRQ handler so it must not
  263.     call DOS or anything much else.
  264.   The only thing you should do is use mouse_setcursor() or
  265.     mouse_setcursor_text().
  266.   The function is called with the following set with in mouse_user:
  267.     mouse_user.x = X pos
  268.     mouse_user.y = Y pos
  269.     mouse_user.but = button status'   (bit 0=left  1=right)
  270.   The function must return with 'RET'.
  271.   You do not need to preserve regsiters.
  272. -----------------------------------------------------------------------------
  273. Function: mouse_setpos(word x,word y)
  274. Expects:  (x,y) = new mouse position
  275. Outputs: nothing.
  276. Notes:
  277.   Sets a new position of the mouse.  The mouse may be hidden or visible.
  278. -----------------------------------------------------------------------------
  279. Grafix Text Services
  280. -----------------------------------------------------------------------------
  281. Function: g_loadfnt(char * fntname)
  282. Expects:
  283.   fntname = filename of font file (*.FNT)
  284. Outputs:
  285.   if successful:
  286.     EAX = address of FONT location.
  287.   if not successful:
  288.     EAX = -1 (ERROR)
  289. Notes:
  290.   g_loadfnt() will alloc RAM for the font and set it as the current font
  291.     if successful.
  292.   The DWORD returned can be used with g_setfnt() in case you have more
  293.     than one font loaded.
  294.   To free the font just call free() with the DWORD returned from g_loadfnt().
  295. -----------------------------------------------------------------------------
  296. Function: g_setfnt(byte * buffer)
  297. Expects:
  298.   buffer = DWORD (or (byte*) same thing!) that was returned from g_loadfnt()
  299. Outputs: nothing.
  300. Notes:
  301.   Sets current font to what ever is in buffer.
  302. -----------------------------------------------------------------------------
  303. Function: g_putch(word x,word y,byte char)
  304. Expects:
  305.   (x,y) = top-left cord to print char
  306.   char = char to print
  307. Outputs: nothing.
  308. Notes:
  309.   Uses current font to print one char at (x,y).
  310. -----------------------------------------------------------------------------
  311. Function: g_printxy(word x,word y,byte * str1)
  312. Expects:
  313.   (x,y) = top-left cord to print string
  314.   str1 = string to print (not formatted)
  315. Outputs: nothing.
  316. Notes:
  317.   Uses current font to print string at (x,y).
  318. -----------------------------------------------------------------------------
  319. Function: g_printf(word x,word y,byte * str1,...)
  320. Expects:
  321.   (x,y) = top-left cord to print string
  322.   str1 = string to print (formatted)
  323.   ... = other paras needed by printf
  324. Outputs: nothing.
  325. Notes:
  326.   Uses current font to print string at (x,y).
  327. -----------------------------------------------------------------------------
  328. Misc stuff
  329. -----------------------------------------------------------------------------
  330. Function: g_hline(word x,word y,word len,dword col)
  331. Expects:
  332.   (x,y) = top-left pixel to start drawing horizontal line.
  333.   len = length of line to draw
  334.   col = color to draw
  335. Outputs: nothing.
  336. Notes:
  337.   Supports multi-depth modes.
  338. -----------------------------------------------------------------------------
  339. Function: g_vline(word x,word y,word len,dword col)
  340. Expects:
  341.   (x,y) = top-left pixel to start drawing vertical line.
  342.   len = length of line to draw
  343.   col = color to draw
  344. Outputs: nothing.
  345. Notes:
  346.   Supports multi-depth modes.
  347. -----------------------------------------------------------------------------
  348.  
  349. Appendix's
  350.  
  351. Appendix A:  How to use the grafix library.
  352.  
  353.      The basic idea behind these functions is that you create an image to
  354.   be displayed on the screen and then have it copied to the video RAM with
  355.   g_copy().  The driver will handle cases like keeping the mouse on the
  356.   screen (which will not even blink during g_copy()).  First you setup
  357.   the screen using g_getmode() and g_setmode().  Then alloc yourself enough
  358.   RAM for the temparea where you will create image to be displayed.  Tell
  359.   the video functions where this temparea is using g_setbuf().  Then
  360.   when ever you have an image ready to be displayed simply call g_copy().
  361.   Make sure to use t_setmode() to return back to text mode so that
  362.   the grafix functions can free any buffers used.
  363.  
  364. Appendix B: Using the mouse functions in text mode.
  365.  
  366.      Using the mouse driver in text mode is a little akward.  First call
  367.   mouse_init() as you always should (do it only once ever time a program
  368.   is used).  Then simply use t_setmode() to setup which mode you want to
  369.   use.  Then use mouse_setcursor_text().  Now you can call mouse_on()
  370.   and mouse_off().  When the callback feature (ie: mouse_setuser()) calls
  371.   your function the (x,y) coords within the struct will NOT represent the
  372.   current X,Y of the cursor in cel rows/columns.  Instead it represents
  373.   the current pixel (x,y) assuming that each cell is 8x8 (regardless of
  374.   what it really is).  So basically divide the X and Y by 8 to find
  375.   it's cell value.
  376.  
  377. Keep in touch with my page at http://www.globalserve.net/~subdeath
  378. E-Mail : subdeath@globalserve.net
  379.  
  380.